Udyam Aadhaar Verification API

The following document highlights the details of the Udyam Aadhaar Verification API.

API Description

Objective

The Udyam Aadhaar Verification API validates a Udyam registration number by querying the MSME (Ministry of Micro, Small and Medium Enterprises) database and returns the organisation's details, including its enterprise classification, registered address, and NIC codes.

Input	Output
The Udyam registration number and user consent	The details associated with the Udyam registration certificate. A complete list of fields is provided under the Success Response Details section.

Udyam Registration

Udyam Registration is a system for registering Micro, Small, and Medium Enterprises (MSMEs) in India. The Udyam or MSME registration number is a unique 19-digit identification number assigned to entities registered under this system.

API URL

https://ind-engine.thomas.hyperverge.co/v1/udyamAadhaarVerification

API Endpoint

udyamAadhaarVerification

Overview

The Udyam Aadhaar Verification API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Udyam Aadhaar Verification API.

Headers

Parameter	Mandatory or Optional	Description	Input Format
content-type	Mandatory	The media type for the request payload.	application/json
appId	Mandatory	The application identifier from HyperVerge. You can find the details in the dashboard's credentials tab.	Unique value
appKey	Mandatory	The application key from HyperVerge. You can find the details in the dashboard's credentials tab.	Unique value
transactionId	Mandatory	A unique identifier for tracking a user journey.	Unique value mapped to the user's journey

Inputs

The following table provides the complete information on the parameters used in the request body for the Udyam Aadhaar Verification API:

Parameter	Mandatory or Optional	Type	Description	Input Format	Default Value
udyamReferenceNumber	Mandatory	String	The unique 19-character Udyam registration number of the organisation.	UDYAM-AB-34-1234567	Not Applicable
consent	Mandatory	String	The consent of the user to verify the Udyam registration number.	Y or N	Not Applicable
returnClassificationDate	Optional	String	When set to "yes", this parameter returns the date and year of the organisation's last Udyam classification in the response.	yes or no	no

Request

The following section shows the standard curl request for the Udyam Aadhaar Verification API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/udyamAadhaarVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
    "udyamReferenceNumber": "<Enter_the_Udyam_Reference_Number>",
    "consent": "<Enter_Y_or_N>",
    "returnClassificationDate": "<Enter_yes_or_no>"
}'

Success Response

The following is a sample response from the Udyam Aadhaar Verification API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "message": "Enterprise exists",
        "address": {
            "door_no": "<Door_No>",
            "building": "<Building>",
            "area": "<Area>",
            "block": "<Block>",
            "street": "<Street>",
            "city": "<City>",
            "state": "<State>",
            "district": "<District>",
            "pincode": "<Pincode>"
        },
        "documentId": "<Udyam_Registration_Number>",
        "majorActivity": "<Major_Activity>",
        "enterpriseType": "<Enterprise_Type>",
        "yearOfClassification": "<Year_Of_Classification>",
        "dateOfClassification": "<Date_Of_Classification>",
        "organizationType": "<Organization_Type>",
        "name": "<Organisation_Name>",
        "mobile": "<Mobile_Number>",
        "email": "<Email>",
        "dateOfIncorporation": "<Date_Of_Incorporation>",
        "dateOfCommencement": "<Date_Of_Commencement>",
        "dateOfUdyamRegistration": "<Date_Of_Udyam_Registration>",
        "districtIndustrialCentre": "<District_Industrial_Centre>",
        "msmeDistrictIndustrialCentre": "<MSME_District_Industrial_Centre>",
        "socialCategory": "<Social_Category>",
        "nicData": {
            "nic_2_digit": "<NIC_2_Digit_Description>",
            "nic_4_digit": "<NIC_4_Digit_Description>",
            "nic_5_digit": "<NIC_5_Digit_Description>"
        },
        "enterpriseUnits": [
            {
                "name": "<Organisation_Name>",
                "address": {
                    "door_no": "<Door_No>",
                    "building": "<Building>",
                    "area": "<Area>",
                    "block": "<Block>",
                    "street": "<Street>",
                    "city": "<City>",
                    "state": "<State>",
                    "district": "<District>",
                    "pincode": "<Pincode>"
                }
            }
        ]
    },
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Success Response Details

The following table provides the details of the fields in a success response:

Parameter	Type	Description
message	String	Confirms whether the organisation exists in the MSME database. For example, "Enterprise exists".
address	Object	The registered address of the organisation, including door number, building, area, block, street, city, state, district, and pincode.
documentId	String	The Udyam registration number provided in the request.
majorActivity	String	The primary business activity of the organisation, such as "Services" or "Manufacturing".
enterpriseType	String	The latest enterprise classification of the organisation, such as "Small", "Medium", or "Large".
yearOfClassification	String	The financial year of the organisation's last Udyam classification. Returned only when returnClassificationDate is set to "yes".
dateOfClassification	String	The date of the organisation's last Udyam classification (YYYY-MM-DD). Returned only when returnClassificationDate is set to "yes".
organizationType	String	The legal structure of the organisation, such as "Private Limited Company" or "LLP".
name	String	The registered name of the organisation.
mobile	String	The mobile number associated with the organisation.
email	String	The email address associated with the organisation.
dateOfIncorporation	String	The date on which the organisation was incorporated.
dateOfCommencement	String	The date on which the organisation commenced operations.
dateOfUdyamRegistration	String	The date on which the organisation was registered with Udyam.
districtIndustrialCentre	String	The District Industrial Centre (DIC) associated with the organisation.
msmeDistrictIndustrialCentre	String	The MSME District Industrial Centre associated with the organisation.
socialCategory	String	The social category of the organisation, such as "General".
nicData	Object	The National Industrial Classification (NIC) codes of the organisation at the 2-digit, 4-digit, and 5-digit levels.
enterpriseUnits	Array	The name and address details of all enterprise units of the organisation.

Failure Response

The following is a sample response when no records are found for the provided Udyam registration number:

{
    "statusCode": 400,
    "status": "failure",
    "error": "Udyam Registration Number does not exist",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are some error responses from the Udyam Aadhaar Verification API:

Incorrect Udyam Format

{
  "message": "Input Validation Error: does not meet minimum length of 1",
  "statusCode": 400,
  "status": "failure"
}

Incorrect Consent Format

{
  "message": "Input Validation Error: does not meet minimum length of 1",
  "statusCode": 400,
  "status": "failure"
}

Bad Request

{
  "statusCode": 400,
  "status": "failure",
  "error": "Bad Request",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

User Consent is N

{
  "statusCode": 400,
  "status": "failure",
  "error": "Consent should be provided",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing/Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

An error response from the Udyam Aadhaar Verification API contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: does not meet minimum length of 1	The udyamReferenceNumber or consent parameter in the request has an incorrect format.	Verify the format of the udyamReferenceNumber and consent fields in the request body.
400	Bad Request	The request is malformed or contains invalid parameters.	Recheck the request body and headers for any formatting issues.
400	Consent should be provided	The user's consent is mandatory to process the request. The consent parameter was set to "N".	Set the consent parameter to "Y" in the request body.
400	Missing required request parameters.	One or more mandatory request parameters are missing from the request body.	Verify that udyamReferenceNumber and consent are included in the request body.
400	Udyam Registration Number does not exist	The Udyam registration number provided in the request is invalid or does not exist in the MSME database.	Verify the Udyam registration number and resubmit the request.
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values.	Verify and provide valid credentials from the dashboard's credentials tab.
403	Access Denied	The request does not have the necessary permissions to access the Udyam Aadhaar Verification API.	Contact the HyperVerge team for resolution.
500	Internal Server Error	An unexpected error occurred on the server.	Check the request headers or contact the HyperVerge team for resolution.